The
REST API for the Queue service is available at the account, queue, and
message levels. In this section, you learn about the Queue service REST
API with specific examples. You also learn to interact with the Queue
service programmatically, and you explore the queue methods in the
available storage client libraries.
The REST API enables you
to make HTTP calls to the Queue service and its resources. REST is an
HTTP-based protocol that lets you specify the URI of the resource as
well as the function you want to execute on the resource. Every REST
call involves an HTTP request to the storage service and an HTTP
response from the storage service.
NOTE
Due to frequent changes
to the Windows Azure Storage service API, the URL parameters may not be
exactly the same as the most recent API version. But conceptually, the
variation in the REST API shouldn't be significant. For the exact
parameter lists, please refer to the Windows Azure SDK documentation
shipped with the SDK.
1. Request
The Queue service REST API's HTTP request components are described in the following sections.
1.1. HTTP Verb
The HTTP verb represents
the action or operation you can execute on the resource indicated in
the URI. The Queue service REST API supports the following verbs: GET,
PUT, POST, HEAD, and DELETE. Each verb behaves differently when
executed on a different resource.
1.2. Request URI
The request URI
represents the URI of a resource you're interested in accessing or
executing a function on. Example resources in the Queue service include
accounts, queues, and messages. An example URI for creating a queue
named logsqueue in an account named proazurestorage is
PUT http://proazurestorage.queue.core.windows.net/logsqueue
The HTTP berb PUT instructs the service to create the queue, and the URI points to the resource that needs to be created.
1.3. URI Parameters
The URI parameters are the
extra parameters you specify to fine-tune your operation execution.
They may include operation parameters or filter parameters for the
results. In the Queue service API, the URI parameters depend on the
type of resource and the HTTP verb used. For example, a URI for
retrieving a list of queues from an account looks like this:
GET http://proazurestorage.queue.core.windows.net/?comp=list
The HTTP verb GET
instructs the Queue service to retrieve results, and the parameter
?comp=list specifies that the data requested is a list of queues.
1.4. Request Headers
Request headers follow
the standard HTTP 1.1 name-value pair format. Depending on the type of
request, the header may contain security, date/time, metadata, or
instructions embedded as name-value pairs. In the Storage service REST
API, the request header must include the authorization information and
a Coordinated Universal Time (UTC) timestamp for the request. The
timestamp can be in the form of either an HTTP/HTTPS Date header or the
x-ms-Date header.
The authorization header format is as follows:
Authorization="[SharedKey|SharedKeyLite] <Account Name>:<Signature>"
Where SharedKey|SharedKeyLite is the authentication scheme, <Account Name> is the storage service account name, and <Signature> is an HMAC of the request computed using the SHA256 algorithm and then encoded by using Base64 encoding.
To create the signature, you follow these steps:
Create the signature string for signing. The signature string for the Storage service request consists of the following format:
VERB\n
Content - MD5\n
Content - Type\n
Date\n
CanonicalizedHeaders
CanonicalizedResource
where VERB is the uppercase HTTP verb such as GET, PUT, and so on; Content — MD5 is the MD5 hash of the request content; CanonicalizedHeaders
is the portion of the signature string created using a series of steps
described in the "Authentication Schemes" section of the Windows Azure
SDK documentation (http://msdn.microsoft.com/en-us/library/dd179428.aspx); and CanonicalizedResource is the storage service resource in the request URI. The CanonicalizedResource
string is also constructed using a series of steps described in the
"Authentication Schemes" section of the Windows Azure SDK documentation.
Use the System.Security.Cryptography.HMACSHA256.ComputeHash() method to compute the SHA256 HMAC-encoded string.
Use the System.Convert.ToBase64String() method to convert the encoded signature to Base64 format.
Listing 1 shows an example request header that sets the metadata values of a queue.
Example 1. Request Header
PUT /myfirstazurequeue?comp=metadata&timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 04:33:45 GMT
x-ms-meta-createdBy: tejaswi
x-ms-meta-creationDate: 6/16/2009
Authorization: SharedKey proazurestorage:
spPPnadPYnH6AJguuYT9wP1GLXmCjn0I1S6W2+hzyMc=
Host: proazurestorage.queue.core.windows.net
Content-Length: 0
|
In listing 1,
the request header consists of x-ms-date, x-ms-version,
x-ms-[name]:[value] and Authorization values. x-ms-date represents the
UTC timestamp, and x-ms-version specifies the version of the storage
service API you're using. x-ms-version isn't a required parameter, but
if you don't specify, you have to make sure the operation you're
calling is available in the default version of the Queue service.
Before making the REST call, be sure you match the operation you're
calling with the API version it's supported in. It's always safe to
match the operation with the version to get the expected results. The
x-ms-meta values represent the queue metadata name-value pairs the
operation should set. The last header value is the Authorization
SharedKey used by the Storage service to authenticate and authorize the
caller.
NOTE
Unlike the Blob service REST API, the Queue service REST API doesn't support HTTP 1.1 conditional headers.
1.5. Request Body
The request body consists
of the contents of the request operation. Some operations require a
request body, and some don't. For example, the Put Message operation
request body consists of the message data in XML format, whereas the
Get Messages operation requires an empty request body.
2. Response
The HTTP response of the Queue service API typically includes the following components.
2.1. Status Code
The status code is the HTTP
status code that indicates the success or failure of the request. The
most common status codes for the Queue service API are 200 (OK), 201
(Created), 204 (No Content), 400 (BadRequest), 404 (NotFound), and 409
(Conflict).
2.2. Response Headers
The response headers include all
the standard HTTP 1.1 headers plus any operation-specific headers
returned by the Queue service. The x-ms-request-id response header
uniquely identifies a request. Listing 2 shows an example response header for a List Queues operation.
Example 2. List Queues Response Header
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: ccf3c21c-7cca-4386-a636-7f0087002970
Date: Tue, 16 Jun 2009 04:47:54 GMT
|
2.3. Response Body
The response body consists
of data returned by the operation. This data is specific to each
operation. For example, the List Queues operation returns the list of
queues in an account, whereas the Get Messages operation returns the
messages in a queue. Listing 3 shows an example of the response body for a List Queues operation. The response contains four queues.
Example 3. List Queues Response Body
<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults AccountName="http://proazurestorage.queue.core.windows.net/">
<MaxResults>50</MaxResults>
<Queues>
<Queue>
<QueueName>testq</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq</Url>
</Queue>
<Queue>
<QueueName>testq1</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq1</Url>
</Queue>
<Queue>
<QueueName>testq2</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq2</Url>
</Queue>
<Queue>
<QueueName>testq3</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq3</Url>
</Queue>
</Queues>
<NextMarker />
</EnumerationResults>
|
|
To test the REST API, I recommend using the Fiddler Tool available at www.fiddler2.com/fiddler2/. In this book, I use this tool to trace client/server communications.
|
|
